Summary

This PR introduces router-specific bound Next.js SDK integration APIs for @contentful/optimization-nextjs:

• App Router: createNextjsAppRouterOptimization() from @contentful/optimization-nextjs/app-router
• Pages Router client components: createNextjsPagesRouterOptimization() from @contentful/optimization-nextjs/pages-router
• Pages Router server handoff: createNextjsPagesRouterOptimization() from @contentful/optimization-nextjs/pages-router/server

Consumers can now bind Optimization SDK configuration once in an app-local module and use the returned OptimizationRoot, OptimizationProvider, OptimizedEntry, route trackers, App Router proxy, or Pages Router getServerSideOptimizationProps() across server and client rendering boundaries.

The change also brings in the isomorphic SSR provider/runtime foundation needed for those APIs: React Web can render personalized content during SSR from snapshot state, then hydrate into the live browser SDK without app code branching on typeof window.

It also extends the React Web OptimizedEntry render-prop contract with OptimizedEntryRenderContext and getMergeTagValue, exposes runtime/presentation helpers used by SSR handoff and tracking, replaces the older Next.js SSR/Hybrid reference apps with App Router and Pages Router implementations, and refreshes docs, package exports, CI, scripts, unit tests, and browser E2E coverage around the new router-specific integration path.

Credit

Credit to Tim's feat/ssr-isomorphic-provider branch and PR #354 for the isomorphic SSR foundation adopted here, including OptimizationRuntime, SnapshotRuntime, runtime package subpaths, server-renderable OptimizationProvider, serverOptimizationState first-paint handoff, SSR variant-rendering fixes, injected-SDK first-paint fixes, and JavaScript-disabled SSR validation.

Example usage

App Router

// lib/optimization.ts
import { createNextjsAppRouterOptimization } from '@contentful/optimization-nextjs/app-router'
import { getAppConsent } from './consent'

export const { proxy, NextAppAutoPageTracker, OptimizationRoot, OptimizedEntry } =
  createNextjsAppRouterOptimization({
    clientId: process.env.NEXT_PUBLIC_CONTENTFUL_OPTIMIZATION_CLIENT_ID ?? '',
    environment: process.env.NEXT_PUBLIC_CONTENTFUL_OPTIMIZATION_ENVIRONMENT ?? 'main',
    locale: 'en-US',
    defaults: { consent: false, persistenceConsent: false },
    server: {
      enabled: true,
      consent: ({ cookies }) =>
        getAppConsent(cookies) ? { events: true, persistence: true } : false,
    },
    trackEntryInteraction: { views: true, clicks: true, hovers: true },
  })

// proxy.ts
export { proxy } from '@/lib/optimization'

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico|api).*)'],
}

Pages Router

// lib/optimization.ts
import { createNextjsPagesRouterOptimization } from '@contentful/optimization-nextjs/pages-router'

export const { NextPagesAutoPageTracker, OptimizationRoot, OptimizedEntry } =
  createNextjsPagesRouterOptimization({
    clientId: process.env.NEXT_PUBLIC_CONTENTFUL_OPTIMIZATION_CLIENT_ID ?? '',
    environment: process.env.NEXT_PUBLIC_CONTENTFUL_OPTIMIZATION_ENVIRONMENT ?? 'main',
    locale: 'en-US',
    defaults: { consent: false, persistenceConsent: false },
    trackEntryInteraction: { views: true, clicks: true, hovers: true },
  })

Architectural and design changes

• Adds router-specific public Next.js SDK entrypoints for /app-router, /pages-router, and /pages-router/server.
• Uses conditional package exports so /app-router resolves to the automatic server implementation in React Server Component contexts and the client implementation in browser/client contexts.
• Keeps the package root and /client as router-neutral React Web client surfaces.
• Keeps /server, /esr, /request-handler, /tracking-attributes, and /api-schemas as lower-level escape hatches for custom flows.
• Moves App Router request work into the bound proxy/server implementation: request consent, cookies, headers, server Optimization data, entry resolution, merge-tag profile reads, tracking attributes, anonymous-ID persistence, and serverOptimizationState handoff.
• Adds a Pages Router server helper that builds request context from getServerSideProps, calls the request-bound SDK, writes or clears ctfl-opt-aid, returns serializable props.contentfulOptimization, and avoids duplicate initial page events when the server already emitted one.
• Adopts the isomorphic runtime model from ✨ feat(react-web): Isomorphic OptimizationProvider for SSR (NT-3560) #354: SSR uses a read-only snapshot runtime, while hydrated browser rendering upgrades to the live SDK.
• Removes NextjsOptimizationState in favor of serverOptimizationState handoff through root/provider components, automatic App Router handoff, or Pages Router pageProps handoff.
• Extends React Web OptimizedEntry render props from (resolvedEntry) to (resolvedEntry, context), where context.getMergeTagValue is available to rich text renderers.
• Adds runtime subpaths for core/web packages and public presentation helpers for optimized-entry tracking/root runtime behavior.
• Updates package export maps, dual declaration generation, bundle-size budgets, CI path filters, root scripts, and implementation names around the new router-specific outputs.
• Adds App Router, Pages Router, request-handler, runtime, React Web, Web SDK, and browser E2E coverage for the new contracts.

Isomorphic SSR foundation

• Adds OptimizationRuntime, SnapshotRuntime, createSnapshotRuntime, and runtime package subpaths for core/web.
• Makes OptimizationProvider / OptimizationRoot render during SSR from serverOptimizationState.
• Allows useOptimization() and OptimizedEntry to resolve personalized content during SSR from snapshot state, then switch to the live SDK after hydration.
• Fixes SSR first-paint variant rendering by seeding snapshot/current optimization state before client effects run.
• Preserves injected-SDK first paint when serverOptimizationState is provided.
• Aligns SnapshotRuntime consent gating with the live SDK.
• Carries forward the SSR/no-JS behavior needed by the Next.js App Router and Pages Router reference apps.

Benefits to consumers

• Less integration boilerplate for App Router and Pages Router consumers.
• One app-local import surface works across App Router server and client components.
• Pages Router gets a single helper for request binding, state handoff, cookie persistence, and initial page-event deduplication.
• Server-to-browser state handoff is harder to forget or duplicate.
• Entry rendering, interaction tracking, and merge-tag rendering use the same OptimizedEntry render-prop shape across server and browser rendering.
• Manual APIs remain available when an app needs direct request SDK control.

Benefits to maintainers

• The recommended Next.js integration path is split by actual Next.js router model instead of by the older SSR/Hybrid examples.
• Server/client boundary behavior is easier to test because the bound factories own the contract.
• The isomorphic runtime boundary from ✨ feat(react-web): Isomorphic OptimizationProvider for SSR (NT-3560) #354 gives React Web one provider model for SSR first paint and client takeover.
• Docs can explain primary App Router and Pages Router paths, with lower-level APIs documented as escape hatches.
• Reference implementations now exercise the preferred public APIs directly.
• CI filters, root scripts, and E2E docs now match the implementation names that reviewers and consumers see.

Reference implementation rendering improvements

• Replace nextjs-sdk_ssr and nextjs-sdk_hybrid with nextjs-sdk_pages-router and nextjs-sdk_app-router.
• Add App Router wiring through an app-local createNextjsAppRouterOptimization() module, exported proxy, layout-level OptimizationRoot, and NextAppAutoPageTracker.
• Add Pages Router wiring through an app-local createNextjsPagesRouterOptimization() module, a server-only getServerSideOptimizationProps() helper, and _app.tsx state handoff.
• Extract shared EntryCardContent rendering so server and client entry cards use the same rich text, nested-entry, click-target, and test-attribute behavior.
• Pass getMergeTagValue from OptimizedEntry render props into rich text render options, aligning merge-tag rendering with the resolved entry/profile context.
• Run the shared browser E2E suite for CSR, hydration, SSR, server-resolved variants, and JavaScript-disabled SSR behavior in both Next.js router implementations.

Breaking change

NextjsOptimizationState is removed from the client entrypoint. Pass server optimization data through OptimizationRoot or OptimizationProvider via serverOptimizationState, use createNextjsAppRouterOptimization() to let the App Router bound root/provider handle server-to-browser state handoff automatically, or use createNextjsPagesRouterOptimization() with getServerSideOptimizationProps() to pass Pages Router state through pageProps.

[NT-3560]